Cap a failed observation's error_message and reserve the openarmature_ namespace - #288

Implements proposal 0119, accepted at spec v0.116.0. It closes the two error-channel edges 0118 left open.

The cap

A failed observation's error_message is now subject to the §5.5.5 per-value byte cap on all four mapped provider observations (Generation, Embedding, Tool, Retriever). It was written verbatim before this: 0118 classified the field for gating without saying it was subject to truncation, so a provider returning a very large exception string (an echoed HTML error page) rendered in full.

It takes the contract's direct-application arm rather than its inheritance arm. The OTel surface defines no error_message span attribute, so the value arrives untruncated and the observer that writes it applies its own payload_byte_cap, rather than inheriting a cap from an upstream OTel truncation that never happened. Re-applying a second cap to an already-truncated value would move the marker and misreport its byte total, which is why the two arms source the cap differently.

Both surfaces of the Tool arm are capped. A failed Tool observation renders the same harvested string twice, once in metadata.error_message and once as the observation's statusMessage. §5.5.5 governs payload-classified values rather than payload-classified fields, so capping one while the other still carried the whole exception would defeat the cap. Spec confirmed this reading after the work was done: an implementation that caps only the metadata copy is non-conforming, and §8.7 gains a sentence naming statusMessage as the case in point. The remaining statusMessage writes take the error category, a classification token, and stay uncapped.

The omission arm is unchanged. §6's prohibition on surfacing the message through statusMessage is scoped to substituting for an omitted message, so a withheld message still leaves statusMessage null on a Tool failure. Under the default posture (disable_provider_payload=True) the field is absent entirely per 0118, so the cap is observable only where payloads are enabled.

The reserved keys

openarmature_ joins openarmature. and gen_ai. as a reserved caller-metadata namespace prefix, and four exact names (error_type, error_message, token_budget, token_budget_exceeded) join the reserved set, which grows from 29 to 33.

With error_message absent under the default posture, an unreserved caller key of that name would otherwise land unopposed in the very field 0118 requires to be absent, reintroducing through the metadata channel the leak the gate closes.

Pre-1.0 behavioral change: a caller passing invocation_metadata with a key beginning openarmature_, or with any of those four names, is now rejected at the invoke() boundary with ValueError where it previously passed.

Testing

Seven cases across six tests, each mutation-verified. Eight mutants run, all killed.

Two of them mattered. Reverting the cap at each of the four sites individually left the embedding and rerank arms green: the first pass covered only the LLM and Tool handlers, and a passthrough mutation of the shared helper (which breaks all four sites at once) produced exactly two failures rather than four. The suite would have accepted a two-arm implementation of a four-arm rule. Both arms now have tests, each verified to kill only its own case, and the passthrough mutant now trips all four.

Ahead of the pin

Spec v0.116.0 is beyond the current v0.112.0 pin, so the behavior ships unit-tested and the conformance.toml entry and fixtures ride the pin bump, matching the precedent in this cycle.

No fixture can drive the Tool arm today: the conformance adapter exposes no tool-calling node, so that arm is unit-tested only. Reported to spec rather than filing a fixture that would be deferred on arrival.

Correction (2026-09-03): the struck sentence is wrong. The conformance adapter has driven tool calls since 0092: calls_tool with a mock_tool block is a supported directive, mock_tool: {raises: {error_type, message}} produces a ToolCallFailedEvent carrying the fixture's own message, and fixture 098 case 2 already drives exactly that into a Langfuse Tool observation and asserts error_message in its metadata. It runs green. The real gap is narrower: fixture 160 carries no Tool case, and one is writable today against existing machinery. Corrected in the CHANGELOG and retracted to spec. Fixture 160's other five cases span Embedding, Generation, and Retriever, and would have caught the two-arm gap independently; they land at the pin bump.